2 Downloading and Deploying EM CLI

Requirements

Before downloading the EM CLI client, ensure that the following system requirements have been met:

• Enterprise Manager 12c Cloud Control framework

• Java version 1.6.0_43 or greater

• Workstation running Solaris, Linux, HPUX, Tru64, AIX, or Windows with NTFS

Downloading and Deploying the Client for Standard EM CLI

To download the client for standard EM CLI only:

1. Obtain the standard EM CLI client kit emclikit.jar using one of the following methods:

   • Download this kit from any 12c Cloud Control installation at the following location:

     /em/public_lib_download/emcli/kit/emclikit.jar
     

   • Download this kit from the Cloud Control console:

     • From the Setup menu, select Command Line Interface.

     • In the EM CLI Standard section, click the Download the EM CLI Standard Kit to your workstation link.

2. Enter the following command to ensure that you have the correct Java in your PATH:

   which java
   

   This should show the Java in $JAVA_HOME/bin.

3. Set your JAVA_HOME environment variable and ensure that it is part of your PATH. You must be running Java 1.6.0_43 or greater. For example:

   setenv JAVA_HOME /usr/local/packages/j2sdk1.6.0_43
   
   setenv PATH $JAVA_HOME/bin:$PATH
   

4. Install the standard EM CLI kit in any directory either on the same system as the OMS or on any system in your network (download the emclikit.jar file to that system):

   java -jar emclikit.jar client -install_dir=<emcli_client_dir>
   

   The EM CLI client is installed in <emcli_client_dir>.

5. Execute emcli help setup from the EM CLI home (the directory where you have installed EM CLI) for instructions on how to use the setup verb to configure the client for a particular OMS.

Downloading and Deploying the Client with the Script Option

To download the client for standard EM CLI as well as Interactive and Script EM CLI:

1. Obtain the EM CLI client kit emcliadvancedkit.jar using one of the following methods:

   • Download this kit from any 12c Cloud Control installation at the following location:

     https://your_em_host:port/em/public_lib_download/emcli/kit/
     

   • Download this kit from the Cloud Control console:

     • From the Setup menu, select Command Line Interface.

     • In the EM CLI with Script Option section, click the Download the EM CLI with Script option kit to your workstation link.

2. Enter the following command to ensure that you have the correct Java in your PATH:

   which java
   

   This should show the Java in $JAVA_HOME/bin.

3. Set your JAVA_HOME environment variable and ensure that it is part of your PATH. You must be running Java 1.6.0_43 or greater. For example:

   setenv JAVA_HOME /usr/local/packages/j2sdk1.6.0_43
   
   setenv PATH $JAVA_HOME/bin:$PATH
   

4. Install the advanced EM CLI kit in any directory either on the same system as the OMS or an any system in your network (download the emcliadvancedkit.jar file to that system):

   java -jar emcliadvancedkit.jar client -install_dir=<emcli_client_dir>
   
   

   The EM CLI client is installed in <emcli_client_dir>.

5. Execute emcli help sync from the EM CLI home (the directory where you have installed EM CLI) for instructions on how to use the sync verb to configure the client for a particular OMS.

   Sync establishes communication with the OMS and ensures that the OMS and all information associated with it are available through the CLI.

Using Basic Operational Verbs

Immediately after installation, only basic operational verbs are available:

• argfile — Execute an EM CLI verb where the verb and any options are contained in a file.

• help — Access command-line help for EM CLI verbs.

• login — Log in and establish a session with the OMS.

• logout — Log out of EM CLI client from Enterprise Manager.

• setup — Configure EM CLI to function with a specific OMS.

  (See Connecting the EM CLI Client to OMS for important information about this verb.

• status — Show EM CLI setup details

• sync — Synchronize the EM CLI client with an OMS.

• version — List EM CLI verb versions or the EM CLI client version.

EM CLI incorporates a comprehensive command-line help system that provides various levels of assistance. Available from any EM CLI client installation, the help system provides a listing of all available verbs, descriptive overviews for each verb, syntax, as well as usage examples. The command-line help is the definitive EM CLI information source.

./emcli help

./emcli help login

$>./emcli

emcli> help()

emcli>help('login')

Connecting the EM CLI Client to OMS

You must run the setup verb to connect the EM CLI client to the OMS running the EM CLI Management Services. Running setup installs all available verb-associated command-line help from the EM CLI Management Service. If you have installed EMCLI with the Script option, you can use the sync command instead of the setup command.

You can use one EM CLI client installation to function with multiple OMSes. However, at any time, EM CLI can function with a particular OMS. For either scenario, you need to set up the EM CLI client once for each OMS. You also need to subsequently set the EMCLI_STATE_DIR environment variable to the directory that was specified as the client directory for the particular OMS.

To connect the EM CLI client to OMS:

1. Understand the syntax of the setup and sync verbs and their options by entering the following commands or referring to the respective verbs in Chapter 4, "Verb Reference":

   • Command-line EM CLI:

     ./emcli help setup
     

   • Script and Interactive EM CLI:

     ./emcli help sync
     

2. Enter the setup verb with at least the minimally required parameters as shown in the following examples:

   • Command-line EM CLI:

     ./emcli setup -url=http://myworkstation.example.com:em_port/em    -username=em_user
     

   • Script and Interactive EM CLI:

     ./emcli sync -url=http://myworkstation.example.com:em_port/em    -username=em_user -trustall
     

     If you have already downloaded certificates, you can specify them using the environment variable EMCLI_CERT_LOC. In this case, the -trustall option is not needed.

   Note:

   Specify the URL you are using to log in to Enterprise Manager through the browser.

   As you observed from step 1, the setup verb has several options, including the following important options:

   • -autologin

   • -noautologin

   In autologin mode, if a session times out, EM CLI automatically logs you in. In the default noautologin mode, if no EM CLI command executes within the 45-minute default session time-out period, you need to log in using the login verb to be able to execute the verbs.

3. Enter your user password for Enterprise Manager when prompted after the EM CLI client connects with the EM CLI Management Services.

After running the setup verb, the message "Emcli Setup Successful" appears, and you are ready to begin using EM CLI.

Configuring an HTTP Proxy Environment

If you are planning to use EM CLI through an HTTP proxy server, you need to set an additional environment variable, EMCLI_OPTS, that supplies EM CLI with the requisite proxy host and port information. The following examples illustrate setting the EMCLI_OPTS environment variable for both Windows and UNIX operating systems.

>set EMCLI_OPTS=-Dhttp.proxyHost=<proxy host> -Dhttp.proxyPort=<proxy port>

>setenv EMCLI_OPTS "-Dhttp.proxyHost=<proxy host> -Dhttp.proxyPort=<proxy port>"

Configuring Log File Settings for EM CLI

EM CLI creates log files to record informational and error messages generated during operation. Not all of the logs in the following examples are necessarily present. Logs are created as needed and are appended — they are preserved between invocations of EM CLI. You can safely delete log files any time without affecting the EM CLI operation. The logs will help you troubleshoot any run-time errors.

The following examples show possible log file locations:

<EM_CLI_Instance_Home>/.emcli.log
<EM_CLI_Instance_Home>/.emcli.log.1

<EM_CLI_Instance_Home> refers to the directory specified by the -dir option in the latest running of the setup verb (with an appended .emcli sub-directory). The current <EM_CLI_Instance_Home> directory can be identified by executing the status verb to display the setup summary.

Log files are limited to a maximum of 0.5 MB. EM CLI alternates between the two log files — as each file reaches the 0.5 MB limit, EM CLI begins writing to the other file, overwriting the oldest log file after emcli.log.1 has been filled for the first time.

user.home/.emcli/.emcli.log
user.home/.emcli/.emcli.log.1

local.dir/.emcli/.emcli.log
local.dir/.emcli/.emcli.log.1

HTTPS Trusted Certificate Management

For authenticating an OMS during the SSL server authentication phase of an HTTPS connection handshake, EM CLI searches for trusted certificates in the following key stores:

CONFIG_DIR/.emcli/.localkeystore
user.home/.emcli/.keystore
JRE_HOME/lib/security/cacerts

CONFIG_DIR is the directory specified by the -dir option in the latest running of the setup verb (with an appended .emcli sub-directory).

JRE_HOME in a JDK installation is typically JAVA_HOME/jre.

The JDK keytool command can manage the key stores. For more information about this tool, see the security documentation for your Java VM installation, or at the time of this writing:

http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html

Not all of the key stores in the list above will necessarily be present.

Secure Clients

You can provide credentials to EM CLI in one of two ways:

• Provide credentials at the time of use. See the login and logout verbs for information on credentials.

• Make credentials persistent on the host system where the EM CLI client is running, as might be the case when executing EM CLI verbs from a shell script.

Secure Mode for the EM CLI Setup

The EM CLI client installs certain configuration files and a client-side implementation of verbs on the client system. The EM CLI client configuration files contain information such as the OMS URL, Enterprise Manager user names, and Enterprise Manager passwords.

By default, the EM CLI client is set up in secure mode. In this mode, EM CLI does not store any Enterprise Manager or SSO passwords on the client disk. The command emcli setup -noautologin sets up the EM CLI client in secure mode. By default, -noautologin is true. Therefore, you do not need to specify it if you want to set up the EM CLI client in secure mode. In secure mode, if the EM CLI session times out due to inactivity, explicit login (using the login verb) is required before invoking any verb.

If you want to set up EM CLI in the insecure auto-login mode, you can use the emcli setup -autologin command. In this mode, if an EM CLI session times out due to inactivity, EM CLI automatically re-establishes the session when a verb needs to execute. However, if you explicitly logged out by running emcli logout, you need to explicitly log in again using emcli login.

• For information on the -noautologin option, see the setup verb on page 4-461.

• For information on logging in, see the login verb on page 4-342.

• For information on logging out, see the logout verb on page 4-343.